home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 May: Tool Chest / Developer CD Series May 1996 (Tool Chest) (Apple Computer) (1996).iso / Tool Chest / Development Tools & Languages / HyperCard Related / APDA HyperCard Toolkits / HyperCard Video Toolkit 2.0 / HVT #2 / Advanced Material / Video Sources / XCMD.HowToUse.doc < prev    next >
Encoding:
Text File  |  1995-02-07  |  6.5 KB  |  167 lines  |  [TEXT/MPS ]
  1. XCMD and XFCN: The Magic Hooks That Extend HyperTalk
  2.  
  3. (This documentation by Ted Kaehler, 14 July 87, HyperCard 1.0.1 and later)
  4.  
  5. Dan Winkler has created an interface that allows powerful new commands 
  6. to be added to HyperCard "in the field."  When a command in a script 
  7. cannot be found, HyperCard looks for a resource of type XCMD with 
  8. the same name as the unknown command.  Likewise, when a function cannot
  9. be found, HyperCard looks for a resource of type XFCN.  Consider XCMDs
  10. and XFCNs to be extensions of stack scripts.  Whenever a handler (for a 
  11. command or function) is not found in a stack script, HyperCard
  12. immediately looks for a XCMD or XFCN in that stack.  The total 
  13. inheritance order is: Button (or Field), Card, Stack, stack XCMD, Home,
  14. home XCMD, HyperCard.  An XCMD or XFCN is a code resource with no 
  15. header bytes (just like a desk accessory).  You can move them from 
  16. file to file with ResEdit, ResCopy or with any other resource moving tool.
  17.  
  18. The only thing passed into an XCMD or XFCN is a pointer to a XCmdBlock.  
  19. It looks like this:
  20.  
  21.   XCmdPtr = ^XCmdBlock;
  22.   XCmdBlock =
  23.     RECORD
  24.       paramCount:  INTEGER;                  { number of arguments }
  25.       params:      ARRAY[1..32] OF Handle;   { the arguments }
  26.       returnValue: Handle;                   { the result of this XCMD }
  27.       passFlag:    BOOLEAN;                  { pass the message on? }
  28.  
  29.       entryPoint:  ProcPtr;                  { call back to HyperCard }
  30.       request:     INTEGER;                  { what you want }
  31.       result:      INTEGER;                  { the answer it gives }
  32.       inArgs:      ARRAY[1..16] OF LongInt;  { args XCMD sends HyperCard }
  33.       outArgs:     ARRAY[1..16] OF LongInt;  { args HyperCard sends back }
  34.     END;
  35.  
  36. You read the agruments (they are handles to zero terminated strings), 
  37. do whatever the purpose of this XCMD is, and optionally store a 
  38. result into returnValue.  All data values going to and from HyperTalk are
  39. zero-terminated ASCII strings.
  40.  
  41. Resources of type XCMD are commands, and resourcs of type XFCN are 
  42. fuctions that return a value.  If you store a result string into 
  43. returnValue in a command, the user can get it by asking for "the result"
  44. (useful for explaining why there was an error).  In a function, you are
  45. expected to store the answer into returnValue.
  46.  
  47. If passFlag is false (the normal case), this XCMD or XFCN has handled the 
  48. message and the script resumes execution.  If passFlag is true, HyperCard
  49. searches the remaining inheritance chain for another handler or
  50. XCMD with the same name.  This is just like the "pass" control structure
  51. in a script.
  52.  
  53. The second part of the XCmdBlock record has to do with 
  54. calling HyperCard back in the middle of your code to ask a question.
  55. If you wanted manage the call to HyperCard yourself, you would 
  56. fill inArgs with your arguments, put a request code in request,
  57. and JSR to the address in entryPoint.  HyperCard returns the values you
  58. requested in outArgs and a reslut code in result.
  59.   
  60. However, Dan Winkler has packaged the entire range of calls on HyperCard,
  61. so that if you are using Pascal, you can simply call a procedure.  The file
  62. XCmdGlue.inc has the glue procedures.  Handle is always a handle to a
  63. zero-terminated sting.  If a handle is returned, you are responsible for
  64. freeing it.  <<is this true?>>
  65.  
  66. FUNCTION EvalExpr(expr: Str255): Handle;
  67.   Given a HyperTalk expression in ASCII, return a handle to a zero-terminated
  68.   string with the answer.
  69.  
  70. PROCEDURE SendCardMessage(msg: Str255);
  71.   Send a HyperCard message (command) to the current card.
  72.  
  73. FUNCTION GetGlobal(globName: Str255): Handle;
  74.  
  75. PROCEDURE SetGlobal(globName: Str255; globValue: Handle);
  76.  
  77. FUNCTION GetFieldByName(cardFieldFlag: BOOLEAN; fieldName: Str255): Handle;
  78.  
  79. FUNCTION GetFieldByNum(cardFieldFlag: BOOLEAN; fieldNum: INTEGER): Handle;
  80.  
  81. FUNCTION GetFieldByID(cardFieldFlag: BOOLEAN; fieldID: INTEGER): Handle;
  82.  
  83. PROCEDURE SetFieldByName(cardFieldFlag: BOOLEAN; fieldName: Str255; fieldVal: Handle);
  84.  
  85. PROCEDURE SetFieldByNum(cardFieldFlag: BOOLEAN; fieldNum: INTEGER; fieldVal: Handle);
  86.  
  87. PROCEDURE SetFieldByID(cardFieldFlag: BOOLEAN; fieldID: INTEGER; fieldVal: Handle);
  88.  
  89. PROCEDURE ZeroToPas(zeroStr: Ptr; VAR pasStr: Str255);
  90.   Convert a zero terminated string to a Pascal string.  You create the
  91.   Pascal string and pass it in as a VAR parameter.  Useful for converting
  92.   the arguments of any XCMD to Pascal strings.  (See PasToZero below).
  93.  
  94. FUNCTION  StrToNum(str: Str19): LongInt;
  95.   Convert ASCII of a decimal number to the number.
  96.  
  97. FUNCTION  StrToLong(str: Str19): LongInt;
  98.   Convert ASCII of a decimal number to the number.  Negative numbers not
  99.   accepted.
  100.  
  101. FUNCTION StrToExt(str: Str31): Extended;
  102.  
  103.  
  104. FUNCTION StrToBool(str: Str31): BOOLEAN;
  105.   Convert ASCII "true" and "false" to Pascal booleans.
  106.  
  107. FUNCTION StringLength(strPtr: Ptr): LongInt;
  108.  
  109. FUNCTION StringEqual(str1,str2: Str255): BOOLEAN;
  110.  
  111. FUNCTION StringMatch(pattern: Str255; target: Ptr): Ptr;
  112.  
  113. PROCEDURE ReturnToPas(zeroStr: Ptr; VAR pasStr: Str255);
  114.  
  115. PROCEDURE ScanToReturn(VAR scanPtr: Ptr);
  116.  
  117. PROCEDURE ScanToZero(VAR scanPtr: Ptr);
  118.  
  119. PROCEDURE ZeroBytes(dstPtr: Ptr; longCount: LongInt);
  120.  
  121. PROCEDURE CopyBytes(srcPtr,dstPtr: Ptr; byteCount: LongInt);
  122.   Generally useful for moving data in memory.
  123.   
  124. PROCEDURE DivMod(numerator: LongInt; denominator: INTEGER;
  125.                  VAR quotient: LongInt; VAR remainder: INTEGER);
  126.   Division with remainder.
  127.  
  128. FUNCTION  LongToStr(posNum: LongInt): Str19;
  129.   Convert a longInt to decimal ASCII.
  130.  
  131. FUNCTION  NumToStr(num: LongInt): Str19;
  132.   Convert a longInt to decimal ASCII, using a minus sign for negative
  133.   numbers.
  134.  
  135. FUNCTION  NumToHex(num: LongInt; nDigits: INTEGER): Str19;
  136.   Convert a longInt to hexadecimal ASCII, using a minus sign for 
  137.   negative numbers.
  138.  
  139. FUNCTION ExtToStr(num: Extended): Str31;
  140.  
  141. FUNCTION BoolToStr(bool: BOOLEAN): Str31;
  142.   Convert a boolean to ASCII "true" or "false".
  143.   
  144. FUNCTION  PasToZero(str: Str255): Handle;
  145.   Convert a pascal string to a zero-terminated string.  You'll need to do
  146.   this for any result or argument you return to HyperTalk.
  147.  
  148.  
  149. Here are the files you will need:
  150.  
  151.  HyperXCmd.p
  152.  XCmdGlue.inc
  153.  
  154. Here are the typical MPW commands for compiling an XCMD
  155.  
  156.     pascal -w SendSerial.p
  157.     link -m ENTRYPOINT -o HyperCommands -rt XCMD=222 -sn Main=SendSerial ∂
  158.       SendSerial.p.o "{MPW}"Libraries:interface.o
  159.  
  160. If you don't use any of the routines in interface.o, its just
  161.  
  162.     pascal Flash.p
  163.     link -o HyperCommands -rt XCMD=0 -sn Main=Flash Flash.p.o
  164.  
  165. After executing these, use ResEdit or ResCopy (a resource mover in a HyperCard
  166. stack, like the Font/DA Mover) to move the XCMD or XFCN from HyperCommands
  167. to the proper stack.